feat!: extend options accumulate instead of replacing - #49

Follow-up to #46. Removes the one merge rule in extend that did not do the intuitive thing.

The bug

extend merged options per key, child winning — except invariants, which concatenated. The comment justifying that exception named immutable and then did not protect it:

silently dropping the parent's immutable or invariants would leave the extension quietly laxer than what it extends. An extension can add rules; it cannot shed them.

So a variant that declared immutable replaced the root's list wholesale:

// root
{ immutable: ["issuedAt", "issuedTo"] }
// variant
{ immutable: ["id", "kind"] }   // ← the root's two are gone, with no diagnostic

issuedAt and issuedTo became patchable. Nothing reported it. 0.4.0 shipped a comment in the example telling readers they had to re-state every inherited key, and the reference had to teach it. A rule that has to be taught in three places and whose violation is undetectable is better removed than documented.

The change

Every option accumulates. Nothing is shed.

computed is a map rather than a list, so per-key is its analogue of "add, don't shed": a variant adding a derived field keeps the root's, and one redefining a key overrides that entry alone.

The declaration syntax does not change. You still write immutable: ["id"].

The type-level part

G and I had to become unions of keys rather than readonly tuples. The tuple form does not compile:

TS2344: Type 'readonly [...I, ...I2]' does not satisfy the constraint …
  Type 'keyof $InferObjectOutput<S, {}>' is not assignable to
       'keyof $InferObjectOutput<S & S2, {}> | keyof ComputedOf<A & A2>'

Same failure types.ts already recorded for GeneratedOf: TypeScript will not prove the parent's key set is a subset of the child's through zod's inference chain, even though adding fields only adds keys. The union form composes with I | I2[number] and was verified at one level, across a chain, and when the child omits the option entirely.

The computed merge is typed MergedComputed<A, A2> = Omit<A, keyof A2> & A2, not A & A2 — the runtime is { ...parent, ...child }, so a plain intersection would type a redefined key as Upper & Lower while the value is Lower.

The defect the gate could not see

Writing that merge inline in extend's return type made TypeScript 5.9.3 emit a dangling type parameter into consumers' declarations whenever the root declares no computed — the default shape, and the one this example used:

}, Omit<Record<never, never>, keyof A2> & Record<never, never>, …>;

node_modules/.emit-check/index.d.ts(90,37): error TS2304: Cannot find name 'A2'.
node_modules/.emit-check/index.d.ts(110,37): error TS2304: Cannot find name 'A2'.

7.0.2 emits the same position correctly, so only the consumer compiler saw it. Left in, this ships a .d.ts that fails on any downstream TS 5.9.x build, with no diagnostic on that build's own source.

Fixed by hoisting to a named MergedComputed<A, A2>. Naming it is only half: unexporting the alias was measured to reproduce the identical TS2304, so it joins BaseInstance / ConstructionKey / Sealed / EntityStatic / AbstractEntity / EntityUnion on the documented emit-nameability export list. Both halves are recorded as measurement in index.ts and types.ts.

examples/billing-domain emitted declarations and never type-checked them. TS4020 is an emit-time diagnostic so that class was caught; a dangling type parameter in the output was not. typecheck now feeds the emitted files back through 5.9.3 — deliberately without --skipLibCheck, which was measured to make the step a no-op. That assumption is what let this through, and it is now written down in emit-guards.ts and CLAUDE.md.

BillingDocumentBase also gains a real computed field (period, the accounting period a document falls in), so the TS7056 margin is measured on the branch that spends most — the root's whole computed map serialises inside Omit<…> and again in & A2. Both compilers clean.

Breaking, in two ways

Relaxing is no longer expressible. immutable: [] in a variant does not widen updateInput. It breaks loudly — updateInput shrinks, so the patch call stops typechecking rather than changing behaviour silently. The migration is in the changeset: a field only some variants need locked comes off the root's list and goes on each variant that wants it locked.

Entity.Static and Entity.BaseInstance take unions where they took tuples, so the empty case is never rather than []. Forced by the TS2344 above and not fixable asymmetrically. The builders still constrain real call sites, so hand-written entity declarations are unaffected.

minor, per 0.x.

What got smaller

examples/billing-domain/src/index.ts is shorter: issuedAt/issuedTo gone from both variants' lists, and the three-line comment teaching the old rule deleted rather than rewritten. That deletion is the whole point.

Test plan

• Two tests invert: a variant declaring immutable: [] no longer widens updateInput, and a variant declaring computed keeps the root's
• New: accumulation through a behaviour-only intermediate root; generated accumulation on a root that generates; a variant redefining one computed key overrides that entry alone
• base.test-d.ts pins the type side — a variant cannot shed the root's immutable keys, and a redefined computed key reads as the variant's brand on Entity.Output, which A & A2 would fail
• The instance-level residue is pinned too: a redefined key keeps the root's brand intersected in on the instance, because BehaviourOf is unmapped and TS2425 blocks subtracting from it. Pre-existing, documented in the reference, asserted so it becomes a signal the day it changes
• examples/billing-domain/src/index.spec.ts pins the inheritance behaviourally: patching issuedAt is refused though neither variant mentions it
• format --check · lint · typecheck · test · knip · build — green in CI order, uncached, including the now-four-step consumer pass on 7.0.2 and 5.9.3

One thing left alone

The merged fields are typed S & S2 while the runtime is child-wins — the same class of type lie MergedComputed fixes for the computed map, sitting two lines from the comment describing it. It is pre-existing, and Omit<S, keyof S2> & S2 would spend TS7056 budget on every entity rather than only those with computed fields. Recorded in types.ts as known and why, rather than fixed here.

🤖 Generated with Claude Code